The jfindpanel.tcl library is distributed as part of the jstools package. It consists of procedures to implement a search¡and¡replace dialogue box for text widgets. The central procedure is j:find, which creates the dialogue box and calls the other procedures as necessary.
Currently, these procedures all communicate via global variables with the contents of the j:find fields and checkboxes. I hope to change this in the future so that they will take arguments, to make them more useful independently of each other. This means that you shouldn't count on the calling conventions for these procedures staying constant, except for j:find itself.
This document describes jfindpanel.tcl version 3.6/3.0.
Usage
Accessing the Library
In order to use the jfindpanel.tcl library, it (and any other libraries it depends on) must be in your Tcl auto_path, described in tclvars(n). Information about how to arrange that, and other conventions common to the jstools libraries, is in the Usage section of The jstools Libraries.
Credits and Copyright
Author
Jay Sekora
js@bu.edu
http://shore.net/~js/
Copyright
The library is copyright ⌐ 1992-1994 by Jay Sekora, but may be freely copied and modified for non¡commercial purposes. (Please contact me if you want to use it for a commercial purpose, this may be OK under some circumstances.)
Overview
Procedures
j:find - search¡and¡replace panel
j:find:again - search again for same string
j:find:find_string - find and select string in text widget
j:find:replace - replace selection in text widget with string
j:find:replace_all - change all occurences of string in text widget
j:find
Usage
j:find [options] w
Argument
w is the text widget to search in
Option
-replace bool (default 1)
Description
This procedure brings up a find panel that allows the user to search for text (and, optionally, replace it) in a text widget, w. By default, i.e. if bool is not false, the panel has two entry widgets labelled `Search for:' and `Replace with:', three checkbuttons labelled `Backwards', `Case¡sensitive', and `Regex', and four buttons labelled `Search', `Replace', `Replace All', and `Cancel'. (The default button is `Search'.)
Complete usage documentation for the Find Panel itself (as opposed to the library) is available in The jstools Find Panel.
Unless -replace 0 has been specified, the user will be able to replace the found string by typing a replacement in the `Replace with:' field and clicking on the `Replace' or `Replace All' button. You will want to specify -replace 0 when using the find panel with read¡only (-state disabled) text widgets. If you don't do this, the user will be able to hang your application by trying to replace text in a disabled widget. (This should probably be considered a bug.)
Note that although the find panel is non¡modal, an application can only have one find panel displayed at a time.
j:find:again
Usage
j:find:again w
Argument
w is the text widget to search in
Description
This procedure is used to search for the next occurrence of a string previously entered into a find panel. It has the same effect as clicking on the `Search' button in the find panel, but it doesn't require the find panel to be displayed. It's convenient as a keyboard shortcut.
If no value has been entered into a find panel when this procedure is invoked, it will simply call j:find to display a find panel.
j:find:find_pattern
j:find:replace
j:find:replace_regexp
j:find:replace_all
These procedures are used by the Find Panel. Their communication conventions are not very mature at this point, so you shouldn't rely on them yet. They (or something like them) will become public procedures in a future version of the library.
Evolution
Feel free to report bugs (and feature requests) to me, <js@bu.edu>, and I will try to deal with them. Also, feel free to fix bugs or add features on your own and let me know how you did it.
Bugs and Limitations
* There's no way to do a backwards regular¡expression search.
* Searches are done by making copies of large parts of the text in a widget, so they're extremely wasteful of memory.
* The replacement string is always inserted literally; there should be a way to refer to submatches in a regular¡expression search.
Changes Since Version 3.6/2.0
The ability to use regular expressions is new.
Changes from earlier versions
These procedures used to be in a file called jlibrary.tcl. Starting with version 3.6/2.0, they're in their own independent library.
Future Directions
* Under Tk 4.0, searching should use the text widget's search subcommand; this should make it much more efficient.
* The procedures that actually do the searches should be public, and they should take options rather than looking at global variables to decide what kind of search to perform
* Searches should (perhaps optionally) wrap around.
* You should be able to use more than one Find Panel in an application. The name of a Find Panel should be based on the name of the text widget it searches in. (Perhaps it should be a child, so it'll automatically be destroyed when the text widget is.)
* You should be able to provide a window name for the find panel. If the window doesn't exist, it should be created as a new toplevel; if it does exist, the new find panel should be packed into it (and the `Cancel' button shouldn't be displayed). That would let people created find panels attached to text windows, which might be more intuitive for multi¡window documents.
